a0f921
@@ -149,7 +149,16 @@
public interface Configuration
     void clear();
 
     /**
-     * Gets a property from the configuration.
+     * Gets a property from the configuration. This is the most basic get
+     * method for retrieving values of properties. In a typical implementation
+     * of the <code>Configuration</code> interface the other get methods (that
+     * return specific data types) will internally make use of this method. On
+     * this level variable substitution is not yet performed. The returned
+     * object is an internal representation of the property value for the passed
+     * in key. It is owned by the <code>Configuration</code> object. So a caller
+     * should not modify this object. It cannot be guaranteed that this object
+     * will stay constant over time (i.e. further update operations on the
+     * configuration may change its internal state).
      *
      * @param key property to retrieve
      * @return the value to which this configuration maps the specified key, or
